hash.h File Reference

• Hash class

More...

#include "common.h"

Include dependency graph for hash.h:

Go to the source code of this file.

Classes
struct	RHash
	Hash class. More...

Macros
#define	mrb_hash_ptr(v)
#define	mrb_hash_value(p)
#define	RHASH(hash)
#define	MRB_HASH_IB_BIT_BIT   5
#define	MRB_HASH_AR_EA_CAPA_BIT   5
#define	MRB_HASH_IB_BIT_SHIFT   0
#define	MRB_HASH_AR_EA_CAPA_SHIFT   0
#define	MRB_HASH_AR_EA_N_USED_SHIFT   MRB_HASH_AR_EA_CAPA_BIT
#define	MRB_HASH_SIZE_FLAGS_SHIFT   (MRB_HASH_AR_EA_CAPA_BIT * 2)
#define	MRB_HASH_IB_BIT_MASK   ((1 << MRB_HASH_IB_BIT_BIT) - 1)
#define	MRB_HASH_AR_EA_CAPA_MASK   ((1 << MRB_HASH_AR_EA_CAPA_BIT) - 1)
#define	MRB_HASH_AR_EA_N_USED_MASK   (MRB_HASH_AR_EA_CAPA_MASK << MRB_HASH_AR_EA_N_USED_SHIFT)
#define	MRB_HASH_DEFAULT   (1 << (MRB_HASH_SIZE_FLAGS_SHIFT + 0))
#define	MRB_HASH_PROC_DEFAULT   (1 << (MRB_HASH_SIZE_FLAGS_SHIFT + 1))
#define	MRB_HASH_HT   (1 << (MRB_HASH_SIZE_FLAGS_SHIFT + 2))
#define	MRB_RHASH_DEFAULT_P(hash)
#define	MRB_RHASH_PROCDEFAULT_P(hash)

Typedefs
typedef int	mrb_hash_foreach_func(mrb_state *mrb, mrb_value key, mrb_value val, void *data)

Functions
mrb_value	mrb_hash_new_capa (mrb_state *mrb, mrb_int capa)
	Creates a new, empty hash with a specified initial capacity.
mrb_value	mrb_hash_new (mrb_state *mrb)
	Creates a new, empty hash.
void	mrb_hash_set (mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val)
	Sets or updates a key-value pair in the hash.
mrb_value	mrb_hash_get (mrb_state *mrb, mrb_value hash, mrb_value key)
	Retrieves the value associated with a given key from the hash.
mrb_value	mrb_hash_fetch (mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value def)
	Retrieves the value associated with a given key from the hash, returning a C-provided default value if the key is not found.
mrb_value	mrb_hash_delete_key (mrb_state *mrb, mrb_value hash, mrb_value key)
	Deletes a key-value pair from the hash.
mrb_value	mrb_hash_keys (mrb_state *mrb, mrb_value hash)
mrb_bool	mrb_hash_key_p (mrb_state *mrb, mrb_value hash, mrb_value key)
mrb_bool	mrb_hash_empty_p (mrb_state *mrb, mrb_value self)
mrb_value	mrb_hash_values (mrb_state *mrb, mrb_value hash)
mrb_value	mrb_hash_clear (mrb_state *mrb, mrb_value hash)
mrb_int	mrb_hash_size (mrb_state *mrb, mrb_value hash)
	Returns the number of key-value pairs in the hash.
mrb_value	mrb_hash_dup (mrb_state *mrb, mrb_value hash)
	Creates a new hash that is a duplicate of the given hash.
void	mrb_hash_merge (mrb_state *mrb, mrb_value hash1, mrb_value hash2)
	Merges the contents of hash2 into hash1.
void	mrb_hash_foreach (mrb_state *mrb, struct RHash *hash, mrb_hash_foreach_func *func, void *p)
	Iterates over each key-value pair in the given hash.

Detailed Description

• Hash class

See Copyright Notice in mruby.h

Macro Definition Documentation

mrb_hash_ptr

#define mrb_hash_ptr

(

v

)

Value:

((struct RHash*)(mrb_ptr(v)))

mrb_hash_value

#define mrb_hash_value

(

p

)

Value:

mrb_obj_value((void*)(p))

MRB_RHASH_DEFAULT_P

#define MRB_RHASH_DEFAULT_P

(

hash

)

Value:

(RHASH(hash)->flags & MRB_HASH_DEFAULT)

MRB_RHASH_PROCDEFAULT_P

#define MRB_RHASH_PROCDEFAULT_P

(

hash

)

Value:

(RHASH(hash)->flags & MRB_HASH_PROC_DEFAULT)

RHASH

#define RHASH

(

hash

)

Value:

((struct RHash*)(mrb_ptr(hash)))

Function Documentation

mrb_hash_delete_key()

mrb_value mrb_hash_delete_key ( mrb_state * mrb, mrb_value hash, mrb_value key )

extern

Deletes a key-value pair from the hash.

Removes the entry associated with key from the hash. The hash is modified in place.

Parameters

mrb	The mruby state.
hash	The hash object (mrb_value) to modify.
key	The key (mrb_value) of the entry to delete.

Returns

The value associated with the deleted key if found, otherwise nil.

mrb_hash_dup()

mrb_value mrb_hash_dup ( mrb_state * mrb, mrb_value self )

extern

Creates a new hash that is a duplicate of the given hash.

This function creates a shallow copy of the original hash self. The keys and values themselves are not duplicated, but the internal structure of the hash (entry array, hash table, default values/procs) is copied.

Parameters

mrb	The mruby state.
self	The hash object (mrb_value) to duplicate.

Returns

An mrb_value representing the new duplicated hash.

mrb_hash_fetch()

mrb_value mrb_hash_fetch ( mrb_state * mrb, mrb_value hash, mrb_value key, mrb_value def )

extern

Retrieves the value associated with a given key from the hash, returning a C-provided default value if the key is not found.

If the key is found in the hash, its corresponding value is returned. If the key is not found, the def mrb_value provided to this function is returned. This function does not use the hash's own default proc or default value.

Parameters

mrb	The mruby state.
hash	The hash object (mrb_value) to search.
key	The key (mrb_value) to look up.
def	The default mrb_value to return if the key is not found.

Returns

The associated mrb_value if the key is found, otherwise def.

mrb_hash_foreach()

void mrb_hash_foreach ( mrb_state * mrb, struct RHash * h, mrb_hash_foreach_func * func, void * data )

extern

Iterates over each key-value pair in the given hash.

This function calls the provided callback function func for each entry in the hash h. The iteration order is the insertion order.

The callback function func has the signature: int callback(mrb_state *mrb, mrb_value key, mrb_value value, void *data)

• mrb: The mruby state.
• key: The key of the current hash entry.
• value: The value of the current hash entry.
• data: The user-supplied data pointer passed to mrb_hash_foreach.

If the callback function returns a non-zero value, the iteration stops.

Important: Modifying the hash h within the callback function can lead to undefined behavior if not handled carefully (e.g., using H_CHECK_MODIFIED as done internally for Ruby methods, though direct C API users must be cautious). The H_CHECK_MODIFIED macro within this function is for internal safety when this function is used to implement Ruby methods that might call arbitrary Ruby code during iteration.

Parameters

mrb	The mruby state.
h	A pointer to the RHash structure to iterate over.
func	The callback function to be called for each key-value pair.
data	A void pointer that will be passed to the callback function.

mrb_hash_get()

mrb_value mrb_hash_get ( mrb_state * mrb, mrb_value hash, mrb_value key )

extern

Retrieves the value associated with a given key from the hash.

If the key is found in the hash, its corresponding value is returned. If the key is not found, this function considers the hash's default settings:

• If a default proc is set for the hash, it is called with the hash and key, and its result is returned.
• If a default value is set, that value is returned.
• Otherwise (no key found and no default settings), nil is returned. This function may also invoke a user-defined default method on the hash if it has been overridden and no basic default proc/value handles the lookup.

Parameters

mrb	The mruby state.
hash	The hash object (mrb_value) to search.
key	The key (mrb_value) to look up.

Returns

The associated mrb_value, or the result of the default proc, or the default value, or nil if not found and no defaults apply.

mrb_hash_merge()

void mrb_hash_merge ( mrb_state * mrb, mrb_value hash1, mrb_value hash2 )

extern

Merges the contents of hash2 into hash1.

Iterates over hash2 and for each key-value pair, sets it in hash1. If a key from hash2 already exists in hash1, its value in hash1 will be overwritten. hash1 is modified in place.

• hash1 must not be frozen.
• hash2 must be a hash.
• If hash1 and hash2 are the same object, or if hash2 is empty, the function returns without doing anything.
• Write barriers are triggered for keys and values from hash2 as they are inserted into hash1.

Parameters

mrb	The mruby state.
hash1	The hash object (mrb_value) to be modified.
hash2	The hash object (mrb_value) whose contents will be merged into hash1.

mrb_hash_new()

mrb_value mrb_hash_new ( mrb_state * mrb )

extern

Creates a new, empty hash.

This function allocates and initializes a new hash object. The returned hash is empty and ready to have elements added to it.

Parameters

mrb	The mruby state.

Returns

An mrb_value representing the new empty hash.

mrb_hash_new_capa()

mrb_value mrb_hash_new_capa ( mrb_state * mrb, mrb_int capa )

extern

Creates a new, empty hash with a specified initial capacity.

This function allocates and initializes a new hash object, pre-allocating internal structures to hold at least capa elements. This can be an optimization if the number of elements to be stored is known in advance, as it can prevent reallocations.

If capa is 0, it behaves like mrb_hash_new(). An error will be raised if capa is negative or excessively large.

Parameters

mrb	The mruby state.
capa	The initial capacity (number of elements) the hash should be able to hold without needing to resize.

Returns

An mrb_value representing the new empty hash with preallocated capacity.

mrb_hash_set()

void mrb_hash_set ( mrb_state * mrb, mrb_value hash, mrb_value key, mrb_value val )

extern

Sets or updates a key-value pair in the hash.

Associates val with key in the hash. If key already exists, its value is updated. If key does not exist, a new entry is created. The hash is modified in place.

If the key is a MRB_TT_STRING and not frozen, it will be duplicated and the duplicate will be frozen before use. Write barriers are triggered for garbage collection purposes for the key and value.

Parameters

mrb	The mruby state.
hash	The hash object (mrb_value) to modify.
key	The key (mrb_value) for the entry.
val	The value (mrb_value) to associate with the key.

mrb_hash_size()

mrb_int mrb_hash_size ( mrb_state * mrb, mrb_value hash )

extern

Returns the number of key-value pairs in the hash.

Parameters

mrb	The mruby state (unused in the current implementation, but part of MRB_API convention).
hash	The hash object (mrb_value) to get the size of.

Returns

An mrb_int representing the number of entries in the hash.